Repository navigation
Conversation
…t compile time A rewrite around a `graphql!` macro that checks each query or mutation against the bundled Admin schema (2026-10) and generates the types of its variables and result. See MIGRATION.md for the move from 0.10. - Workspace of three crates released together: shopify_api, shopify_api_macros and shopify_api_graphql (schema, analyzer, codegen). - Deprecated fields, arguments, input fields and enum values are compiler warnings with Shopify's reason; directives come from the schema. - Operations go to the version of the schema they were checked against; `shopify-api schema download` stores another version, `check` validates .graphql files. - Tokens: static, client credentials, expiring with refresh; renewed in a task of its own, once for all clones, saved through a TokenStore. - Retries: throttling waits for its cost, 429 for Retry-After, queries after 5xx or network failures, never a mutation. - Pagination, bulk operations, webhooks (verification, subscription sync), OAuth and session tokens, MockTransport for tests. - Errors never hold secrets or signed query strings. - mise.toml for the toolchain and tasks; CI runs `mise run check`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Select the Admin API version with `api-version` in `[package.metadata.shopify_api]`; `graphql!` downloads its schema to `graphql/admin.schema.json` on the next build when it is missing or another version - `shopify-api schema download` reads the version from Cargo.toml and no longer takes `--api-version` - Rename the bundled schema file to `admin.schema.json` - Add `shopify_api_graphql::project` (version lookup, schema source, atomic file writes), behind a `download` feature - Add `toml` and `ureq` dependencies
- No schema ships with the crates. `graphql!` downloads the schema of the crate's API version on first build and again when the version changes. - Default version is the latest stable one. `api-version` in `[package.metadata.shopify_api]` pins it. - `shopify-api schema download --only <files>` keeps only the types and fields those `.graphql` files use. - Crate operations are checked against a trimmed `graphql/internal.schema.json`, and the Admin schema moves to `crates/shopify_api/graphql/`. - Add `.cargo/config.toml` pointing `SHOPIFY_GRAPHQL_SCHEMA` at the test schema.
`--cfg docsrs` turns on `feature(doc_cfg)`, which stable Rust rejects, so the `doc` task failed in CI. docs.rs still sets the flag itself, on nightly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…work Pinning a version that is not out yet, or misspelt, failed with "build once with network access and commit the file", though the download had worked: Shopify answers such a version with a 400 "Invalid API version". - The downloads of `shopify_api_graphql::project` return a `DownloadError`, whose `UnknownVersion` is that answer. - `graphql!` then names the version and suggests a released one. Other failures keep the advice to build with network access. - When the latest version is not out and the one before fails too, the error is the one before's, the one to fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both v4/v2 ran on the deprecated Node 20 runtime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OperationKind::of ended comments at \n only, so "# c\rmutation { … }" read
as a query and was sent again after a 5xx or a network failure. It now
lexes the document: comments end at \r, \n or \r\n (the spec's
LineTerminator), strings and block strings are skipped, and a document it
cannot read to the end (subscription, typo, unbalanced braces) counts as a
mutation, so it is never retried.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A 429's Retry-After was clamped to max_delay (30 s by default), so a 120-300 s cooldown burned every retry early. max_delay now caps only the computed backoff. A Retry-After longer than the new RetryPolicy::max_retry_after (5 min by default) is not waited for: the request ends in Error::Throttled, which now carries that wait in retry_after (the variant is #[non_exhaustive], so this is additive). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
timestamp=-9223372036854775808 overflowed `now - timestamp` in verify_query and verify_app_proxy before the signature was checked. The distance is now an abs_diff, and the timestamp is only read once the HMAC (constant-time verify_slice) holds. Session token exp/nbf checks use saturating arithmetic for the same reason. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- testing::GraphqlRequest: manual Debug, access_token shown as [redacted]. - transport::HttpRequest: the URL is shown without its query string, so a signed bulk-download address no longer leaks its signature. - transport::HttpResponse: secret headers (now also Set-Cookie and Proxy-Authorization) redacted; a Location header loses its query string. - bulk::BulkOperation: url and partial_data_url shown without their query string. - CLI DownloadArgs: access token and client secret redacted. The fields themselves are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
auth.rs spawns the token renewal with tokio::spawn, which needs tokio's `rt` feature; only `sync` and `time` were declared, so `cargo check -p shopify_api --no-default-features --lib` failed with E0425 while reqwest's tokio features hid it in the default build. The crate now declares `rt`. A new `check:features` mise task builds the library with no default features and with each feature alone; CI runs it in its own `features` job, required by "CI is green". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
restricted_to dropped the possible types of interfaces and unions that
no operation selected, so in a cut schema `node { ... on Product { title } }`
made Product the only Node: the fragment always applied and `title`
became `String` instead of `Option<String>`. Decoding an Order then
failed with "missing field title". Interfaces and unions now keep their
whole list of possible types (the names only; the types stay out).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ypes
The analyzer required every selection of a response key to be the same
field with the same arguments, so
`node { ... on Product { label: title } ... on Order { label: name } }`
was refused. Per the spec's FieldsInSetCanMerge, when the two parents are
different object types (never both present), only the shape of the
answer must agree; the field names and arguments may differ. On the same
type or an interface they still must match. The shape check stays
strict: the two types must be the same (same nullability, lists and
named type), so the merged key keeps a single Rust type.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A response that returns a bulk operation's signed url next to an errored field ended in Error::Graphql, whose derived Debug printed the url. Debug now lists the keys of the partial data, not their values. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ry-After Since Retry-After is honored past max_delay, a mocked 429 with Retry-After: 300 made the test client sleep five minutes. An internal RetryPolicy flag, set only by testing::client, retries at once; a wait beyond max_retry_after still ends in Error::Throttled. Production clients are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RFC 9110 allows Retry-After as an HTTP date. Only seconds were read, so a dated 429 was retried after the 1s backoff. The three HTTP-date forms are now parsed with chrono (already a dependency), the wait is counted from now, a past date is no wait, and max_retry_after applies as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The spec (All Variable Usages Are Allowed) lets a nullable variable fill a non-null location only with a non-null default. `$id: ID = null` was taken as a default and passed. A "gid://..." default is still accepted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql-parser keeps input objects in a map, so in
{id: "1", title: "old", title: "new"} the first title vanished before
validation while the text sent to Shopify kept both. A small scan of
the text applies Input Object Field Uniqueness before analysis.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`... on ProductVariant { x: image { a: url } } ... on Collection { x: image
{ a: originalSrc } }` was refused: the subselections of `x` merged on Image
and lost the fact that their parents can never both be present. Each
place now carries the parent types above it; two places whose chains
differ by two object types at some depth only need the same shape
(FieldsInSetCanMerge / SameResponseShape). Same type or an interface
still needs the same field and arguments.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GraphQL Ruby answers a variable that does not validate with its whole
value under extensions.value, so a signed originalSource reached logs
through {:?} of Error::Graphql. GraphqlError's Debug now shows the
message, locations, path, extensions.code and only the names of the
other extensions. errors that are neither a list nor a string keep
their value in extensions.value instead of the message.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Error documented that secrets never appear in it; decode and HTTP errors did not hold to it. - Error::Decode (and the token endpoint and variables errors) keep the path and the kinds of value, not the values serde quotes: 'invalid type: string "…"' becomes 'invalid type: string'. - Error::Http shows at most 1 KiB of the body, with address query strings, token-like words (shp…_ prefixes, JWTs, long mixed letters and digits) and the values of secret-named entries replaced by [redacted], in Display and Debug. The whole body stays available through Error::raw_http_body and the new raw_body: RawBody field, whose Debug shows its length only. - The doc of Error states what is guaranteed and what is shown as is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
chrono's %y pivots at a fixed year, so in 2069 a Retry-After of 'Wednesday, 06-Nov-69 …' did not parse, and later two-digit years would be read a century off. The century is now chosen from the current date: the latest year with those two digits that is not more than 50 years ahead (RFC 9110 §5.6.7). The weekday must still match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The duplicate input field scan searched a Vec of the fields given so far, quadratic in the size of one object: 100,000 fields took about 50 s in a debug build, 0.2 s with a HashSet per object. Same results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Arguments were compared as text, and graphql-parser writes 1.0 as 1
and keeps input objects in a map, so x: f(a: 1) and x: f(a: 1.0), or
{a: 1, b: 2} and {b: 2, a: 1}, were merged while Shopify's GraphQL
Ruby refuses both with fieldConflict.
Values are now compared structurally, by kind (Int, Float, String,
Enum, Boolean, null, variable, list, object): -0.0 is not 0.0, 1.0 is
1.00, a block string is the string it holds. The order of an input
object's fields, which the parser drops, is read back from the text at
the position the parser gives; when it cannot be, the selection is
refused rather than sent. Messages write each value with its kind.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A key selected on two exclusive object types had to name fields of the
same type, so nodes { ... on Product { price: priceRangeV2 { … } }
... on Order { price: totalPriceSet { … } } } was refused although its
answers have one shape. Two places of a key now need the same lists,
nullability and scalar or enum, or two types with subfields; the
subfields of every place are merged, each collected on the type of its
own place, and checked the same way at every depth. Where both places
can be in one answer the field and its arguments must still match.
The merged selection becomes one struct whose fields are those of
every place, optional unless every place selects them; Selection::types
lists the types it is selected on.
Also refuse a field of an object type that has subfields at one place
and none at another ({ shop { name } shop } was accepted).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
is_word keeps '=' and '/' in a word, so 'x=shpat_…' or '/eyJ…' were one word that did not start like a token. Shopify token prefixes and JWTs are now found after any non-alphanumeric character of a word. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…input
Text scrubbing kept missing secrets (escaped quotes, JSON \u escapes,
tabs, escaped slashes, map keys, bulk counts, variables errors). Errors
now never put text they did not write in Display, Debug or source():
- Error::Http shows the status, address, content type and body length;
the body stays in raw_http_body(). The redacted `body` preview is gone.
- Error::Decode: a new path-tracking deserializer (decode.rs) names only
the fields and variants the Rust type declares (&'static str), writes
`[key]` for map keys, and describes the mismatch in its own words with
the line and column. serde's message is in sensitive_detail().
- Error::Variables: one path for Operation::variables, json_variable and
graphql_raw; the Serialize message is in sensitive_detail().
- Error::Auth: the token endpoint's status and a known OAuth code; its
answer is in sensitive_detail().
- Bulk counts, ids, statuses and error codes are not echoed.
- InvalidShop/InvalidApiVersion do not show the text given; addresses
lose their user and password too; GraphQL data/extensions Debug counts
entries instead of naming them.
- Error::Json and From<serde_json::Error> are gone; redact.rs,
serde_path_to_error and thiserror are dropped.
A test builds every variant from secret-bearing input and checks
Display, Debug, {:#?} and the source chain.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`draftOrderCreate: draftOrderCreate(...)` skipped the argument scan: the alias was detected by `alias != name`, so the colon stayed unread and the scan returned no arguments, and input objects in different orders compiled although GraphQL Ruby refuses them (fieldConflict). The colon token now says whether there is an alias. The analyzer docs say where it is stricter than the specification, and why. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`Tuesday, 29-Feb-00 08:49:37 GMT` read as 2100-02-29 first, which does not exist, and the parse gave up before trying 2000: a past Retry-After fell back to the ordinary backoff instead of no wait. The day, month and time are now read in a leap year, the century is chosen, then the date is built. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A "Bulk operations" section in the documentation of `graphql!`: the rules checked, the items and their connections, the variables written into the text, bulk mutations, and what is not checked. The module docs of `bulk`, the README, the CHANGELOG and MIGRATION show the typed path first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A bulk query writes an enum variable bare. A `String` or `raw("…")`
holding `null`, `true` or `false` passed the name check and was sent as
`null` or a boolean: another value than the one given. They now fail
with `InvalidValueReason::ReservedEnumValue` before anything is sent; a
real `null` is still written `null`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A bulk query is sent as text written back from what `graphql-parser` read, and 0.4.1, its latest release, reads `\b` as U+0010 and splits and indents block strings unlike the specification (a lone `\r`, Unicode whitespace). Its values carry no position and input objects are sorted maps, so the original tokens cannot be mapped back reliably. Each string token of a bulk query is now decoded as the specification does and compared with what the parser read; a difference is a compile error that says what to write instead (`\u0008` for `\b`, a quoted string for a block string). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A line's `id` places its children only when it is a string: another value, such as `id: totalInventory`, no longer fails every line with `Error::Decode`. On a node with nested connections, which must select `id` itself, another field aliased `id` is refused at compile time. - Where lines need it, the text sent selects `_shopifyApiTypename: __typename` and lines are routed by that key alone: a `__typename` of the query, aliased or conditional, is left as written instead of merging with an unconditional one. The alias is reserved and refused in a bulk query. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UI tests for a `\b` string, the `_shopifyApiTypename` alias and an `id` alias beside a nested connection. A constant named like a binding of the generated code (`__shopify_api_parent`, `__shopify_api_value0`) fails to compile with E0308: no binding form escapes a constant in scope (`ref`, `mut` and `x @ _` all give E0530), so the prefix is documented as reserved and the error pinned, for bulk and literal code alike. The new files shift trybuild's crate indexes, which the hashed names of five `literal_*` snapshots follow. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enum values `true`, `false` and `null` in a variable, a list and an input field; every GraphQL escape and block strings, in constants and defaults, decoded by the test's own decoder against the value written; a string variable of every code point; `id` aliases of other types on an item and a child; routing by `_shopifyApiTypename` beside a conditional `__typename`. The changelog says what changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql-parser 0.4 measures the common indentation of a block string in bytes over any Unicode whitespace, then cuts each line at that byte: a line indented with U+00A0 (two bytes) beside one indented with U+2003 (three bytes) made `graphql!` panic, bulk or not. Every parse now goes through `analyze::parse`, which first runs the parser's own indentation steps on each block string of the source and refuses one whose cut falls inside a character, at its line and column. The string lexer of the bulk checks moves to `source`, shared. A test compares the check with the parser's panics over a grid of whitespace mixes; UI tests pin the refusal for an ordinary and a bulk operation. The other UI outputs change because trybuild numbers its test crates in file order. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`_shopifyApiTypename: products` and `__x: products` were accepted: the top-level field went straight to `Checker::connection`, without the `check_key` every field of a node goes through. The docs and changelog reserve these aliases in the whole bulk query, so the top-level field is checked as well. Pinned by a unit test and a UI test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The variables section said a `None` is written `null`. A `None` in an optional field of a module's `Variables` leaves the variable out: its argument goes, or takes the variable's default. Only a `null` given as a value (`sort = null`, an inline `Option` that is `None`, a `None` in a list, `null` or `Maybe::Null` in an input object) is written `null`, and it replaces the default. The docs and changelog say so; a test pins the three cases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sport Without `rustls` or `native-tls`, `build` has no transport and the example failed with `NoTransport` under `--no-default-features`. Its body now runs only with a transport feature, the text shown unchanged. `check:features`, which CI's `features` job runs, now also runs the doctests of `shopify_api` without default features. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ion)` Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
verify_session_token takes only the tokens of Shopify admin again: dest
exactly https://{shop}.myshopify.com, iss exactly its /admin, compared
whole (a prefix let https://s.myshopify.com.evil.example/admin pass).
SessionToken::subject is user_id again.
verify_extension_session_token verifies the tokens of checkout and
customer account UI extensions, which any buyer gets, as an
ExtensionSessionToken (shop, customer, claims) that does not exchange
for a token.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…alEq So that a progress callback or a retry predicate can be added after 1.0 without a breaking change. They stay Clone, Debug and Default. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…onnections start_bulk_* only starts and returns the operation; bulk_query* and bulk_mutation start, wait and read. - start_bulk_query takes a text (&str, String), GroupObjects(text) for groupObjects, or a graphql!(bulk(…)) query or its Variables, through the sealed StartBulkQuery trait. run_bulk_query and run_bulk_query_grouped(query, bool) are gone. - run_bulk_mutation and run_bulk_mutation_iter are start_bulk_mutation_text, over any iterator (a slice by reference); run_bulk_mutation_staged is start_bulk_mutation_staged. - A typed bulk query asks for groupObjects only when its item has nested connections: Shopify documents grouping as slower and more likely to time out. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tions
An ignored test, run by mise run test:live, for
products { variants { metafields } media { ... on MediaImage } }: its
items are compared with the raw JSONL regrouped by __parentId. It checks
that Shopify keeps the _shopifyApiTypename alias and the groupObjects
order at the second level. It creates a fixture product, tagged
shopify-api-live-test, when the store has none of that shape.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ackages only The published macro honoured SHOPIFY_API_INTERNAL_TEST_SCHEMA for every package, dependencies included. It now applies only when CARGO_PKG_NAME is shopify_api or shopify_api-tests, the name trybuild gives its projects; any other crate keeps its own schema. Pinned by a unit test and by a probe workspace built with the variable set. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ate only One function names the crate path; every generated item goes through ::shopify_api::__private (Result, Operation, OperationKind, InputObject, Maybe, bulk::BulkQuery, bulk::BulkMutation). The bulk codegen used #krate::Result, which a crate re-exporting shopify_api with a Result of its own shadowed. A probe app that depends only on a facade crate (extern crate facade as shopify_api) with its own Result, Operation and bulk now compiles. A future crate = … stays additive. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…with 0.10 MIGRATION: what to do in order when subscribed in XML, verify_hmac marked JSON only, WebhookSubscription non_exhaustive with new required fields, wait_for_bulk_operation returns Ok with status Failed while the start-wait-read calls fail with Error::Bulk, access_token() then token(), the InvalidApiVersion and Timeout rows, ApiVersion::default() moving from 2026-04 to 2026-10. CHANGELOG: the matching Breaking bullets. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…omer `ExtensionSessionToken::customer` is the GID of a logged-in customer: the `sub` of an admin token, a staff member, stays in `claims()`. And `start_bulk_query` of anything else than a bulk query says so, rather than asking for `From` (`#[diagnostic::do_not_recommend]`). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the names Shopify sorts the whole `name=value` strings of an app proxy request. Sorting by name differs when one name extends another by a byte below `=` (`page`/`page2`, `filter`/`filter.v.price.gte`), so a request Shopify signed was refused. Admin queries keep sorting by name. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A caller that tells a lasting refusal (4xx with an OAuth code) from a passing one (5xx, 408, 429, no code) had to parse the message. Error::Auth now has `status`, `oauth_code` (OAuthErrorCode) and `held` (the failure of a renewal another request ran), with accessors, filled for client credentials, refresh, code exchange, token exchange and the held copies. The Display text is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql! (inline, modules, bulk) and input! take `crate = path` first, so a crate that uses them through a framework re-exporting shopify_api needs no shopify_api in its own Cargo.toml. The default stays ::shopify_api. The path must be absolute; `$crate` is refused, since serde's derive reads it as text. The schema and API version are still those of the calling crate. The trybuild crate names shift with the new UI case, which moves the crate-name hash in five expected outputs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Owner
Author
|
Three fixes from the openshop port onto rc.1 (openshop-rust#36):
No version bump, tag or publish. |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
1.0.0-rc.1is on crates.io. 1.0 is a rewrite. Your GraphQL operations are checked against Shopify's Admin schema while your crate compiles, and their variables and results become Rust types. Around them, the client handles tokens, throttling, bulk operations, webhooks and OAuth.The release candidate is opt-in:
cargo add shopify_apistill installs 0.10.1. I'm waiting for your feedback before tagging 1.0.0. After that tag, a breaking change has to wait for a 2.0. This PR stays open until then. What I'd like to hear about is under Feedback wanted, below.graphql!reference.In 30 seconds
A typo does not reach Shopify. It fails the build:
There is no build script, no generated file and no codegen step. The macro reads one schema file next to your
Cargo.toml.The client runs on Tokio: the default transport and the token renewals need a Tokio runtime.
What's in 1.0
.graphqlfiles1. Operations checked at compile time
graphql!parses the operation and checks it against the schema:The result is a struct generated from the selection, with snake-case fields:
String,IDStringInt,Float,Booleani64,f64,boolJSONserde_json::ValueTwithout!Option<T>[T]Vec<T>DateTime,Money,Decimal…)String, as Shopify sends itEnum results are strings so that a value Shopify adds later doesn't break reading an answer. Enum values you write in the operation (
sortKey: CREATED_AT) are checked.2. Variables and input objects, written as literals
Variables follow the operation as
name = value, and each value is converted to the variable's type:Int;&strorStringfor anID;Vecfor a list;Optionfor a nullable variable.A value of the wrong type fails the build at that value.
Input objects are object literals, checked field by field:
There are four ways to write a field:
title: valuetitle: nullnull: Shopify clears the fieldtitle?: optionSome; forNone, nothing, and Shopify keeps what it hastitle?: maybeshopify_api::Maybe:Value,Null, or nothing forAbsenttitle: optiondoes not compile. Sendingnullfor aNonewould silently clear the field on Shopify's side. The compiler points to the two explicit spellings:These are also compile errors, each pointing at the token:
nullon a non-null field;@oneOfinput with other than exactly one field.For example:
For an enum value known only at run time,
raw(value)sends the string unchecked.input!builds an input object ahead of the call, in a loop for instance. Everyinput!of one GraphQL type has the same Rust type, so values built in different places go in oneVec:Values Shopify would not read as written are refused before anything is sent. In 0.10, a
NaNwent out asnulland cleared the field. Now:Floatmust be finite;Intmust fit in 32 bits;JSONmust not benull.An out-of-range integer literal fails the build. A value known only at run time fails the call with
Error::InvalidValue, which names the place and never the value:invalid value at `$product.metafields[2].value`: not a finite Float.3. Named operations and
.graphqlfilesgraphql! { pub mod name = "…"; }names the generated types, so functions can take and return them. One block holds several modules. A module'sVariablesruns as it is, and the module names each input type it uses:pub mod order = file("graphql/order.graphql");reads the operation from a file.shopify-api check graphql/*.graphqlchecks those files the same way, in CI or for other tools that use them.4. Typed bulk operations
graphql!(bulk("…"))checks a bulk query against Shopify's bulk rules as well as the schema:edges { node }only;first,last,afterorbefore;idon each node that has nested connections.A bulk query that Shopify would reject, or silently read differently, fails the build:
The results are generated types too. Each nested connection is a
Vecof its nodes, put back under its parent as the file downloads. Memory holds one top-level object at a time, not the whole export:Shopify takes no variables for a bulk query. The crate writes them into the query text as GraphQL literals, typed and escaped.
A bulk mutation runs over an iterator of its
Variables. Every line is checked before anything is uploaded, and each result line is typed:Untyped bulk methods run any text, such as a query built at run time:
bulk_query_rowsVecbulk_query_streambulk_query_groupedstart_bulk_*wait_for_bulk_operation,cancel_bulk_operation,download_bulk_*5. Schema and API versions
No schema ships with the crate:
graphql/admin.schema.json. Commit it.Shopify::builder(…).api_version(…): every request then goes to that version.To choose the version, pin it:
The schema belongs to each crate. A library that uses
graphql!ships its own file, and a dependency never downloads or writes one. If a library forgets the file,cargo packagefails before it is published.The
shopify-apicommand (cargo install shopify_api --features cli) has two jobs:shopify-api schema downloadrefreshes the file.--shopdownloads the schema your token sees, and--onlycuts the file down to the operations you use.shopify-api checkvalidates.graphqlfiles.6. Tokens
The client handles the renewals:
401.TokenStorehas saved the new token. A failed save is tried again on the next call, which fails withError::TokenStoreuntil it succeeds.7. Throttling and retries
Retries are on by default, four of them:
extensions.cost, up tomax_delay, 30 s by default), then goes again.429waits for itsRetry-After, up tomax_retry_after(five minutes by default). A longer wait ends inError::Throttled { retry_after, … }.5xxor a network failure, with exponential backoff and jitter.5xxor a network failure, since it may have run.RetryPolicy::none()gives 0.10's behaviour: fail at the first throttle.8. Webhooks
Feature
webhooks:Webhook::verifydoes four things:X-prefix;Webhook::verify_with_secrets;event_id(), so you can drop a duplicate delivery;{. The client secret also signs other strings (launch queries, app proxy requests, session tokens), and none of them may pass for a webhook.When
sync_webhook_subscriptionskeeps an XML subscription (same topic and address), it updates it to JSON.9. OAuth and embedded apps
Feature
oauth:ShopifyAppcovers the whole app flow:authorization_url,verify_query,exchange_code);verify_app_proxy);Admin session tokens and extension session tokens are signed with the same secret, but any buyer of the shop can get an extension token. So they verify into two distinct types:
verify_session_tokentakes only admin tokens, and the result can be exchanged for an access token;verify_extension_session_tokenreturns anExtensionSessionToken, which can't be exchanged. A buyer's token never passes for an admin session.10. Pagination, untyped calls, tests, errors
Pagination:
Untyped calls, for operations built at run time:
shopify.graphql(query, variables)returnsdataas aserde_json::Value;graphql_as::<T>reads it as your type;graphql_rawreturns the whole answer,errorsincluded.Tests without the network: feature
testinggives aMockTransport, which records what the client sends and answers what the test says:Errors that keep data out of your logs. An
Errornever shows a response body, a value or map key from an answer, a value of your variables, a query string, or serde's messages. Shopify's ownerrorsanduserErrorsmessages are shown as Shopify wrote them (one may quote part of an invalid variable), and so are the errors of yourTransportandTokenStore:Error::Httpshows the status, the address and the length of the body, and carries Shopify'sX-Request-Id;Error::Decodeshows the kind of mismatch and the path of the field;raw_http_body()andsensitive_detail()give the rest when you need it.Features:
rustls(default)native-tlswebhooksoauthtestingMockTransportand the signing helpers for testsclishopify-apicommandfullnative-tlsWithout
rustlsornative-tls, plug in your ownTransport.Upgrading from 0.10
1.0 needs Rust 1.88 or newer. Most code changes in three places:
The main renames
Shopify::new(shop, ShopifyAuth::AccessToken(t), ShopifyConfig::default())Shopify::new(shop, Auth::access_token(t))ShopifyConfig { api_version, token_store, … }Shopify::builder(shop).api_version(…).token_store(…)ShopifyAPIErrorErrorshopify.graphql::<T>(…)shopify.graphql_as::<T>(…), orgraphql!post_graphql(featuregraphql-client)graphql!run_bulk_query(q)(which only started it)start_bulk_query(q), orbulk_query_rowsfor the whole cycleTokenStore::save_token(&str, TokenData)TokenStore::save(&ShopDomain, &TokenData)replace_authgraphql!, 2026-10 for untyped callsThese changes need attention:
MIGRATION.mdgives the order.RetryPolicy::none()keeps that behaviour.MIGRATION.md);run_bulk_queriesandrun_bulk_mutations, the concurrent bulk helpers;utils.<name>or<name>.myshopify.com. 0.10 accepted any text.Feedback wanted
Comment on this PR, or open an issue. Please include:
api-versionyou use;I'd most like to hear about:
graphql!in your code:AuthandTokenStoreenough?Ideas for after 1.0. They are additive, so they don't block the release. Tell me which ones you need:
graphql!from another crate. The generated code refers to::shopify_apitoday, so the dependency can't be renamed or re-exported.DateTime,Money,Decimal…), which areStrings today.--api-versionforshopify-api schema download;Status
1.0.0-rc.1published:shopify_api,shopify_api_macros, andshopify_api_graphql, which is internal with no semver guarantee.webhooks,oauthandtestingeach alone;cargo package;cargo deny;MockTransport: none of them reaches the network.mise run test:live). The typed bulk reader relies on two behaviours of Shopify that its guide doesn't show:_shopifyApiTypenamealias is kept in the JSONL file;groupObjectswrites each object right after its parent, at the second level too.ids[]of bulk-action links). It follows Shopify's JS library, but hasn't been checked on a real link.v1.0.0. The tag publishes the three crates.For reviewers
Layout:
crates/shopify_apiis the client;crates/shopify_api_macrosholdsgraphql!andinput!;crates/shopify_api_graphqldoes the schema parsing, the validation and the code generation.Read first:
MIGRATION.mdfor what changes for 0.10 users;crates/shopify_api/docs/graphql.mdfor the macro, its rules and its limits.Check locally:
mise install && mise run checkruns CI's main checks.mise run msrvandmise run auditcover two more jobs.Live tests need a dev store and a token with
read_productsandwrite_products:They may create one product, tagged
shopify-api-live-test, and leave it on the store.Releasing: pushing a
v*tag runs CI, thencargo publish --workspace.This PR replaces shopify_api 1.0: operations checked against Shopify's schema at compile time #32. GitHub closed shopify_api 1.0: operations checked against Shopify's schema at compile time #32 when its branch was renamed to
RC-1.0.0.🤖 Generated with Claude Code